Action: Message

Message actions cause a MIP packet containing user-selectable data to be transmitted. They can be configured for oneshot mode, where one packet is emitted immediately when activated, or for streaming mode, where packets are emitted at a fixed rate while active.

 

Configuration

A message action has several configuration options: the decimation, descriptor set, and a list of descriptors. The decimation controls how often packets are emitted. If set to 0, only a single packet will be emitted (this is oneshot mode). The descriptor set selects the MIP data descriptor set. It must be supported by the device. The list of descriptors selects the data quantities from that descriptor set.

Because a packet can only contain data from one descriptor set, multiple message actions are needed to send data from more than one descriptor set. Configure each one to the same associated trigger so that they all transmit together. Similarly, if multiple-rate data is required, use one message action per data rate.

Oneshot mode

decimation = 0

In this mode, one packet is output per trigger activation. The associated trigger must deactivate and reactivate before another packet will be transmitted.

The primary use case for oneshot mode is to synchronize sampling to an external device (see timing information below). It can also be used to receive notifications from the device when something happens.

Example

To output scaled acceleration, use the following configuration.

  • Descriptor set 0x80 (Sensor Data)
  • Decimation 0 (oneshot mode)
  • Descriptors 0x04

See Synchronizing sampling to an external device for a more detailed example.

Streaming mode

decimation > 0

This mode behaves similar to the scheduled data streams (i.e. those set up via the 3DM Message Format (0x0C,0x0F) command). One packet is transmitted immediately when activated, just like with oneshot mode. Another packet is transmitted every decimation ticks of the base rate for the selected descriptor set.

Example

To stream scaled accel (0x80,0x04) and scaled gyro (0x80,0x05) data at 100 Hz, use the following configuration.

  • Descriptor set 0x80 (Sensor Data)
  • Decimation 10 (Sensor Data base rate, typically 1000, divided by the desired rate, 100 Hz)
  • Descriptors 0x04, 0x05

 

Event Source

Because of the number of different streaming and event channels, it can be confusing and difficult to identify why a packet was transmitted. Therefore, it is strongly recommended that the Event Source (0xFF,0xD0) field be included as the first field in all event packets. It contains the action ID responsible for its transmission, which can be used to reconfigure the event or disable it entirely. Using this field also allows event data packets to be differentiated from regular streaming packets.

It's also possible to specify the event source field in scheduled streaming data. In this case the action ID will be 0, which is not a valid instance ID (recall that instance IDs start at 1).

Because this is a Shared Data Descriptors, the field will be present even if the number of fields "rolls over" into another MIP packet.

 

Timing Information

Timestamps and Synchronization

To facilitate time synchronization features, all event triggers record and send to actions the timestamp of the last activation. The message action produces a packet that appears to have been created at this time. If any of the supported timestamp fields[1] are included, they will reflect the trigger time. Additionally, data quantities are interpolated using the previous two samples where such interpolation makes sense.

In the case of the GPIO trigger configured for edge mode, the trigger timestamp is a precise hardware timestamp from the time the gpio pin changed state. Because the packets appear to be sampled at time of activation, this provides a mechanism to synchronize sampling to an external device.

GPIO-triggered MIP packets are output at the next event sample tick.

Delta time

The delta time quantities[2] behave similar to scheduled streaming; they report the time since the last packet containing the delta time field. When used with message actions in oneshot mode, they effectively report the time since the last trigger.

The delta time of each message action is unique, as is the delta time of each descriptor set for scheduled streaming. In other words, two message actions containing delta time will not interfere with each other.

 

[1] Timestamp fields are GPS Timestamp (0xFF,0xD3), Reference Timestamp (0xFF,0xD5), and External Timestamp (0xFF,0xD7).
[2] Delta time fields are Delta Time (0xFF,0xD4), Reference Time Delta (0xFF,0xD6), and External Time Delta (0xFF,0xD8).